#%RAML 1.0
title: Mod-Users BL
version: v5.0
baseUri: http://github.com/org/folio/mod-users-bl

documentation:
  - title: Business Logic Users API
    content: A front end for mod-users and mod-permissions

types:
  compositeUser: !include compositeUser.json
  compositeUserListObject: !include compositeUserListObject.json
  loginCredentials: !include loginCredentials.json
  userdata.json: !include userdata.json
  usergroup.json: !include usergroup.json
  permissionUser.json: !include permissionUser.json
  proxyfor.json: !include proxyfor.json
  identifier: !include identifier.json
  errors: !include raml-util/schemas/errors.schema
  updateCredentials: !include updateCredentials.json
  generateLinkRequest: !include generateLinkRequest.json
  generateLinkResponse: !include generateLinkResponse.json
  configurations: !include configurations.json
  passwordResetAction: !include passwordResetAction.json
  passwordReset: !include passwordReset.json
  notification : !include notification.json

traits:
  orderable: !include raml-util/traits/orderable.raml
  pageable: !include raml-util/traits/pageable.raml
  searchable: !include raml-util/traits/searchable.raml
  language: !include raml-util/traits/language.raml
  validate: !include raml-util/traits/validation.raml
  includeable: !include raml-util/traits/includes.raml
  permissionsExpandable:
    queryParameters:
      expandPermissions:
        description:
          Whether or not to expand permissions listings
        type: boolean
        required: false
        default: false
resourceTypes:
  compositeUserResource:
   get:
    description: "Get a user by <<typeName>>"
    is: [
      includeable,
      permissionsExpandable
    ]
    responses:
      200:
        body:
          application/json:
            schema: compositeUser
      400:
        description: "Bad request"
        body:
          text/plain:
            example: "Bad request"
      403:
        description: "Access denied"
        body:
          text/plain:
            example: "Access denied"
      404:
        description: "User not found"
        body:
          text/plain:
            example: "User not found"
      422:
        description: "Unprocessable Entity"
        body:
          application/json:
            type: errors
      500:
        description: "Internal server error"
        body:
          text/plain:
            example: "Internal server error"
  compositeForgottenResource:
    post:
      description: called when a user has forgotten <<resourceTypeName>>
      body:
        application/json:
          schema: identifier
      responses:
        204:
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        422:
          description: "Unprocessable Entity"
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"

/bl-users:
  get:
    description: Get a number of user (and possibly related) records based on criteria in the user and related modules
    is: [
      searchable: {description: "", example: "active=true"},
      pageable,
      includeable
    ]
    responses:
      200:
        body:
          application/json:
            schema: compositeUserListObject
      400:
        description: "Bad request"
        body:
          text/plain:
            example: "Bad request"
      403:
        description: "Access denied"
        body:
          text/plain:
            example: "Access denied"
      500:
        description: "Internal server error"
        body:
          text/plain:
            example: "Internal server error"
  /by-id:
    /{id}:
      type: { compositeUserResource: { "typeName" : "id" } }
      is: [includeable]
  /by-username:
    /{username}:
      type: { compositeUserResource: { "typeName" : "username"} }
      is: [includeable]
  /_self:
    type: { compositeUserResource: { "typeName" : "self reference" } }
  /login:
    post:
      description: Allow a new user to login and return an authtoken, along with a composite user record
      is: [permissionsExpandable, includeable]
      headers:
        User-Agent:
        X-Forwarded-For:
      body:
        application/json:
          schema: loginCredentials
      responses:
        201:
          body:
            application/json:
              schema: compositeUser
          headers:
            x-okapi-token:
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        422:
          description: "Unprocessable Entity"
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /forgotten:
    /password:
      type: {compositeForgottenResource: {"resourceTypeName" : "a password"}}
    /username:
      type: {compositeForgottenResource: {"resourceTypeName" : "a username"}}
  /settings:
    /myprofile:
      /password:
        post:
          description: Allow change password for user
          headers:
            User-Agent:
            X-Forwarded-For:
          body:
            application/json:
              type: updateCredentials
          responses:
            204:
              description: "Successful update"
              body:
                text/plain: !!null
            400:
              description: "Bad request"
              body:
                application/json:
                  schema: errors
            401:
              description: "Unauthorized"
              body:
                text/plain:
                  example: "Unauthorized"
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
  /password-reset:
    /link:
      post:
        description: Generate and send password reset link
        body:
          application/json:
            type: generateLinkRequest
        responses:
          200:
            body:
              application/json:
                type: generateLinkResponse
    /reset:
      post:
        description: "Reset password"
        headers:
          User-Agent:
          X-Forwarded-For:
        body:
          application/json:
            type: passwordReset
        responses:
          204:
            description: "Successful password reset"
          422:
            description: "Unprocessable Entity"
            body:
              text/plain:
                example: "Bad request"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
    /validate:
      post:
        responses:
          204:
            description: "Successful link validation"
          422:
            description: "Unprocessable Entity"
            body:
              text/plain:
                example: "Bad request"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
